<?xml version='1.0'?><!DOCTYPE html PUBLIC><html xmlns='http://www.w3.org/1999/xhtml'>
  <head>
    <title>jMock - Writing Custom Constraints</title>
    <link href='/jmock.css' title='Navigation View' rel='stylesheet' type='text/css' media='screen' />
    <link href='/print.css' title='Print Preview' rel='alternate stylesheet' type='text/css' media='screen' />
    <link href='/print.css' rel='stylesheet' type='text/css' media='print' />
    <meta content='' http-equiv='Content-Type' />
  </head>

  <body>
    <div id='banner'>
      <a href='/index.html'><img src='/logo.gif' id='logo' alt='jMock' /></a>
    </div>

    

    
      <div class='Content2Column' id='center'>
        <div id='content'>
          <h1 class='FirstChild'>Writing Custom Constraints</h1><p>jMock defines several classes and factory functions that define
constraints over the acceptable parameter values of a method invocation.
Sometimes, however, the predefined constraints do not let you specify an
expectation accurately enough to keep your tests flexible. In such cases, you
can easily define new constraints that seamlessly extend the existing
constraints defined by jMock.</p><p>A constraint is an object that implements the <code><a href='/docs/javadoc/org/jmock/core/Constraint.html'>Constraint</a><span class='LinkFootnoteRef'><sup>1</sup></span></code>
interface. It does two things:</p><ul>
  <li>report whether a parameter value meets the constraint (the
    <code>eval</code> method).</li>
  <li>provide a readable description to be included in test failure messages
    (the <code>describeTo</code> method from the <a href='/docs/javadoc/org/jmock/core/SelfDescribing.html'><code>SelfDescribing</code></a><span class='LinkFootnoteRef'><sup>2</sup></span>
    interface).</li>
</ul><p>The <code><a href='/docs/javadoc/org/jmock/core/constraint/package-summary.html'>org.jmock.constraint</a><span class='LinkFootnoteRef'><sup>3</sup></span></code>
package contains many constraint implementations and the programmer can
easily specify their own constraints by writing their own implementations of
the <code>Constraint</code> interface.</p><p>To create a new constraint:</p><ol>
  <li><p>Write a class that implements the <code>Constraint</code> interface.
    The following constraint class tests whether a string starts with a given
    prefix.</p>

    <div class='Source Java'>
    <pre>import org.jmock.core.Constraint;

public class StringStartsWith implements Constraint {
    private String prefix;

    public StringStartsWith( String prefix ) {
        this.prefix = prefix;
    }

    public boolean eval( Object o ) {
        return o instanceof String &amp;&amp; ((String)o).startsWith(prefix);
    }

    public StringBuffer describeTo( StringBuffer buffer ) {
        return buffer.append("a string starting with \"")
                     .append(prefix)
                     .append("\"");
    }
}</pre>
    </div>
  </li>
  <li><p>Write a factory method in your test case that creates an instance of
    your new constraint.</p>

    <div class='Source Java'>
    <pre>public class MyTestCase extends MockObjectTestCase {
    ...

    private Constraint aStringStartingWith( String prefix ) {
        return new StringStartsWith(prefix);
    }
}</pre>
    </div>
  </li>
  <li><p>Use your factory method to create constraints in your tests. The
    following expectation specifies that the error method of the mockLogger
    object must be called once with an argument that is a string starting
    with "FATAL".</p>

    <div class='Source Java'>
    <pre>public class MyTestCase extends MockObjectTestCase {
    ...

    public void testSomething() {
        ...

        mockLogger.expects(once()).method("error").with( aStringStartingWith("FATAL") );

        ...
    }

    private Constraint aStringStartingWith( String prefix ) {
        return new StartsWith(prefix);
    }
}</pre>
    </div>
  </li>
</ol>
        <div class='LinkFootnotes'><p class='LinkFootnotesHeader'>Links:</p><p>1. <a href='http://www.jmock.org/docs/javadoc/org/jmock/core/Constraint.html'>http://www.jmock.org/docs/javadoc/org/jmock/core/Constraint.html</a></p><p>2. <a href='http://www.jmock.org/docs/javadoc/org/jmock/core/SelfDescribing.html'>http://www.jmock.org/docs/javadoc/org/jmock/core/SelfDescribing.html</a></p><p>3. <a href='http://www.jmock.org/docs/javadoc/org/jmock/core/constraint/package-summary.html'>http://www.jmock.org/docs/javadoc/org/jmock/core/constraint/package-summary.html</a></p></div></div>
	    <div class='Meta'>
	      <p><a href='http://cvs.jmock.codehaus.org/jmock/website/content/custom-constraints.html'>Document History</a></p>
	    </div>
      </div>
    

    <div class='SidePanel' id='left'>
      <div class='MenuGroup'>
        <h1><a href='/download.html'>Software</a></h1>
        <ul>
          <li><a href='/download.html'>Download</a></li>
          <li><a href='/repository.html'>Anonymous CVS Access</a></li>
          <li><a href='/license.html'>Project License</a></li>
          <li><a href='/CHANGELOG'>Change Log</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/docs.html'>Documentation...</a></h1>
        <ul>
          <li><a href='/getting-started.html'>Getting Started</a></li>
          <!-- <li><a href="">Frequently Asked Questions</a></li> -->
          <li><a href='/docs/javadoc/index.html' target='jmock-javadoc'>JavaDocs</a></li>
          <li><a href='http://www.mockobjects.com'>More about Mock Objects</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>User Support</h1>
        <ul>
          <li><a href='/mailing-lists.html'>Mailing Lists</a></li>
          <li><a href='http://jira.codehaus.org/secure/BrowseProject.jspa?id=10336'>Issue Tracker</a></li>
          <li><a href='/news-rss2.xml'>News Feed (RSS 2.0)</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/development.html'>Development...</a></h1>
        <ul>
          <li><a href='/how-to-contribute.html'>How to Contribute</a></li>
          <li><a href='/team.html'>Development Team</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>Related Sites</h1>
        <ul>
          <li><a href='http://www.mockobjects.com'>Mock Objects</a></li>
          <li><a href='http://www.junit.org'>JUnit</a></li>
          <li><a href='http://www.nmock.org'>nMock</a></li>
          <li><a href='http://www.codehaus.org'>Project hosted by Codehaus</a></li>
        </ul>
      </div>
    </div>

    
  </body>
</html>